home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / program / tmtpl37o.zip / MANUAL.OS2 < prev    next >
Text File  |  1996-10-17  |  32KB  |  1,001 lines
  1.                    Pascal Lite Compiler for OS/2
  2.                         [ Version 0.33 ]
  3.  
  4.                     TMT Development Corporation
  5.  
  6. Introduction
  7. ------------
  8.  
  9. The TMT Pascal Lite compiler is a fast compiler for the Pascal language.
  10. The compiler emits 32-bit code and supports many language extensions
  11. from Borland Pascal (BP), as well as more powerful extensions.
  12.  
  13. The compiler requires a floating point co-processor.
  14.  
  15. This manual consists of the following parts:
  16.  
  17.     - compiler installation and running
  18.     - configuration file
  19.     - memory organization
  20.     - calling convention
  21.     - implemented language description:
  22.          - restriction
  23.          - extensions
  24.          - incompatibilities
  25.     - units description:
  26.          - DOS
  27.          - CRT
  28.          - USE32
  29.          - ERRCODE
  30.          - DEBUG
  31.          - STRINGS
  32.          - OS2ORD
  33.          - DOSCALL
  34.          - OS2PMAPI
  35.     - troubleshooting
  36.     - run-time error codes
  37.  
  38.  
  39. Compiler installation and running
  40. ---------------------------------
  41.  
  42.    The Pascal Lite distribution is contained in the tmtplos2.zip archive.
  43.    Please, read the license.doc file before the installation.
  44.  
  45.    Follow these instructions to run the installation process.
  46.  
  47.       - create the \TMTPLOS2 directory on one of the drives (we will call
  48.         it the x: drive) using the command:
  49.             x> md TMTPLOS2
  50.  
  51.    NOTE::: DO NOT INSTALL THE DOS AND THE OS/2 VERSIONS OF THE COMPILER INTO
  52.      THE SAME DIRECTORY. Because of file name conficts, this will make one
  53.      of the versions unusable.
  54.  
  55.       - copy the tmtplos2.zip file into the TMTPLOS2 directory:
  56.  
  57.             x> copy  tmtplos2.zip x:\TMTPLOS2
  58.             x> x:
  59.             x> cd \TMTPLOS2
  60.  
  61.       - run the PKUNZIP program to decompress the TMTPLOS2.ZIP
  62.  
  63.             x:\TMTPLOS2> pkunzip -d tmtplos2
  64.  
  65.         (the switch "-d" unpacks with subdirectories)
  66.  
  67.       - modify the PATH statement in the autoexec.bat, to include the
  68.                 x:\TMTPLOS2\BIN
  69.          subdirectory, if you so desire.
  70.  
  71.          and the INCLUDE_PATH statement in x:\TMTPLOS2\BIN\TMTRC.CFG for
  72.          the desired resources.
  73.  
  74.       - goto to \TMTPLOS2\EXAMPLES\OS2\HELLO
  75.         compile the simple test program, "HELLO.PAS", and run it:
  76.  
  77.            x:\TMTPLOS2\EXAMPLES\OS2> plt hello
  78.            x:\TMTPLOS2\EXAMPLES\OS2> hello
  79.  
  80.       - read the entire manual.os2 file before using the compiler for
  81.         any "real" application development.
  82.  
  83.  
  84. Contents of the distribution
  85. ----------------------------
  86.  
  87.    documentation:
  88.  
  89.       manual.os2         - description of the PLT compiler for OS/2.
  90.       license.doc        - license agreement
  91.       readme             - this file
  92.  
  93.    executable:
  94.  
  95.      subdirectory BIN\ contains following files:
  96.  
  97.        pltos2.cfg         - compiler configuration file
  98.        plt.exe            - the PLT compiler under OS/2
  99.        tmtrc.exe          - TMT resource compiler for OS/2 *
  100.        tmtrc.msg          - TMT resource compiler message file *
  101.        tmtrc.mac          - TMT resource compiler prologue file *
  102.        tmtrc.cfg          - TMT resource compiler configuration file *
  103.  
  104.        * not in the free version.
  105.  
  106.    standard library object modules:
  107.  
  108.      subdirectory UNITS\ contains unit files with following extensions:
  109.          .FPD - for DOS version
  110.          .FPU - for OS/2 version
  111.          .FPL - for OS/2 version (for .DLL's)
  112.  
  113.       arg                - commmand line parsing unit
  114.       crt                - crt unit
  115.       debug              - post-mortem dump unit and other debugging
  116.                            functions
  117.       dos.fpd            - dos unit
  118.       doscall            - low-level DOS interface and OS/2
  119.       os2ord             - OS/2 function ordinal numbers (OS/2 version only)
  120.       os2pmapi           - OS/2 presentation manager interface (OS/2 version only)
  121.       errcodes           - run-time error codes
  122.       strings            - strings unit
  123.       system             - system unit
  124.  
  125.       also in this directory contains files:
  126.           STUB.EXE    - stub for OS/2 executables
  127.           DOS32.EXE   - DOS32 extender
  128.           STUB32.EXE  - stub for DOS32 extender
  129.           PASSTUB.EXE - PMODE-based extender
  130.  
  131.    example:
  132.  
  133.      subdirectory EXAMPLE\DOS\ contains following examples for MS DOS:
  134.  
  135.        HELLO\ - example "Hello, World" program
  136.        FLAME\ - example of direct works with I/O ports and physical
  137.                 memory
  138.        VESADEMO\ - example of import and usage VESA.OBJ file from
  139.                   DOS32 libraries.
  140.  
  141.      subdirectory EXAMPLE\OS2 contains following example for OS/2:
  142.  
  143.        HELLO\ - example "Hello, World" program
  144.        SKELETON\ - example simple presentation manager application
  145.  
  146.       subdirectory EXAMPLE\LIN_EQ contains example of multidimensional
  147.       open arrays usage
  148.  
  149.    supplemential files:
  150.        full distribution of DOS32 extender for the MS DOS
  151.        version of Pascal/Lite
  152.  
  153.  
  154.    Running the compiler:
  155.    --------------------
  156.  
  157. The compiler is invoked with the "plt" command:
  158.  
  159.   plt [switches] <main file>
  160.  
  161. where the following switches can be used:
  162.  
  163.     -m   - make modified units (default option)
  164.     -b   - build the whole program
  165.     -c   - single compilation (without linkage)
  166.  
  167.     -t<target> - define target system for compiling
  168.         <target> = DOS - for DOS executables (default under DOS)
  169.         <target> = OS2 - for OS/2 executables (default under OS2)
  170.         <target> = OS2:FS - for OS/2 full screen executables
  171.         <target> = OS2:PM - for OS/2 presentation manage executables
  172.         <target> = OS2:DLL - for OS/2 dynamic link libraries
  173.  
  174. The suite of compiled units (*.FPx) will be created in the same
  175. directory as the sources, and the executable file will be created in the
  176. current directory (if the switch -c is not used).
  177.  
  178.  
  179. Configuration file
  180. ------------------
  181.  
  182. Before a compilation the compiler reads the settings from the special file -
  183. pltos2.cfg. It searches for one at the beginning of the current directory and
  184. then, if it doesn't find one, in the starting directory.
  185.  
  186. The configuration file "pltos2.cfg" contains the compilation parameters:
  187. one command per line.  Empty line are possible.  Comment lines are started with
  188. the ';' symbol.
  189.  
  190. The following parameters can be used in the pltos2.cfg:
  191.  
  192.     toggle settings:
  193.  
  194.        w+       - turn on the puting of warning messages
  195.        r+       - turn on the range checking
  196.        q+       - turn on the overflow checking
  197.        i+       - turn on then automatic input/output result checking
  198.        t+       - typed pointers
  199.        x+       - extended syntax
  200.        v+       - strict var checking
  201.        optreg+  - turn on the register optimization
  202.        optfrm+  - turn on the stack frame optimization
  203.        opt+     - turn on all optimization (optreg+ & optfrm+)
  204.  
  205.     Default settings: w+, r+, q+, i+, t-, x+, v+, opt+.
  206.  
  207.     file path search specification:
  208.  
  209.        srcpath    <search_path> - specifies path for the source file search
  210.        objpath    <search_path> - specifies path for the object file (.FPD,
  211.                                   .FPU, .FPL) and STUBs search
  212.        objimppath <search_path> - specifies path for the OBJ import file
  213.                                   search by use of a $L directive
  214.  
  215.  
  216.        pseudo-devices SYS: and SRC: can be used in the path line:
  217.  
  218.          SYS: means the PLT compiler directory,
  219.          SRC: means the application program directory.
  220.  
  221.        defaults:  srcpath     src:;sys:
  222.                   objpath     src:;sys:
  223.                   objimppath  src:;sys:
  224.  
  225.  
  226.     buffer size specification:
  227.  
  228.        objmax <size>    - specifiies the size of the buffer for object
  229.                           modules (fpd-files). This parameter must be
  230.                           about one and a half times the size of the
  231.                           largest fpd-file from the project.
  232.  
  233.        exemax <size>    - specifies the maximum size of the executable
  234.                           module.
  235.  
  236.  
  237.        defaults:   objmax 333000
  238.                    exemax 256000
  239.  
  240.        These values are enough for ordinary work.  But if you receive
  241.        a message about overflowing of these buffers, you'll have to
  242.        increase them.
  243.  
  244.     stack size specification:
  245.  
  246.        stack <stack_size> - specifies size of the application stack
  247.        default: 32000
  248.  
  249.     start up block (stub) name specification:
  250.  
  251.        stub  <stub_name>  - specifies the STUB name for the linker.
  252.                             default: STUB.EXE for OS/2 targeted compilation
  253.                             and DOS32.EXE for DOS targeted compilation
  254. +++0.30
  255.                             use the OBJPATH option to specify the seacrh path
  256.                             for the stub files
  257. ---0.30
  258.  
  259.     Symbol definition:
  260.  
  261.        def <symbol name>
  262.  
  263. +++0.30
  264.            The following symbols are predefined:
  265.                 __TMT__ :    always
  266.                 __DOS__ :    for DOS target
  267.             *   __OS2__ :    for all OS/2 targets
  268.             *   __DLL__ :    for .DLL targets
  269.             *   __PM__  :    for OS/2 Presentation manager targets
  270.             *   __FS__  :    for OS/2 Full screen targets
  271.             *           --   OS/2-hosted compiler only
  272. ---0.30
  273.  
  274.     error message format specification:
  275.  
  276.  
  277.  
  278.        errmw+ - specifies the MetaWare Pascal format of the error message:
  279.  
  280.                    E "HELLO.PAS" L4/C16: type mismatch
  281.  
  282.  
  283.        errmw- - specifies the BP-like format of the error message:
  284.  
  285.                    textcolor (lightred+'a');
  286.                               
  287.                    Error: HELLO.PAS (line 4, col 16): type mismatch
  288.  
  289.        This parameter allows use of the MultiEdit program as a shell
  290.        when the errmw+ parameter is set.
  291.  
  292.        The default is:  errmw-
  293.  
  294.      output of the Dos32 logo specification:
  295.  
  296.        logo+  -  enables output of the Dos32 logo during the running of
  297.                  the emitted program.
  298.        logo-  -  disables output of the Dos32 logo during the running of
  299.                  the emitted program.
  300.  
  301.        The default is: logo+
  302.  
  303. Memory organization under DOS32 extender
  304. ----------------------------------------
  305.  
  306. The PLT compiler uses the Dos32 extender for a protected-mode program.
  307. The full distributive of Dos32 is in the DOS32 subdirectory.
  308. This distributive contains all information about program execution
  309. under the 32-bit mode.  Here some important issues are presented.
  310.  
  311. The segment registers are not used in the protected mode.  Instead all
  312. address space is separated on 4Kb pages starting from the zero address.
  313. Every page has a physical equivalent in the special table (the physical
  314. address might not be equal to the logical address).  In such a case the
  315. logical address 0 corresponds to the beginning of the program code.
  316. Therefore if you try to access the physical address (video memory and so
  317. on), you will not succeed.
  318.  
  319. Nevertheless, access to the physical addresses is possible, because
  320. the Dos32 extender reflects physical addresses into another set of special
  321. address pages.  To find the logical address from physical, you have to add
  322. the value of the special _zero varible from the SYSTEM unit to the physical
  323. address.
  324.  
  325. For example:
  326.  
  327.         procedure clr_video (filler: char);
  328.            var i: integer;
  329.         begin
  330.            for i := 0 to 80*25-1 do
  331.                mem [_zero+$B8000+i*2] := filler;
  332.         end;
  333.  
  334. This procedure fills the video memory of the VGA adapter with the
  335. filler symbol.
  336.  
  337. Note that the linear address $B8000 is used as the physical address - not
  338. the segment address $B800.
  339.  
  340. Some another special variables are described in the SYSTEM unit.
  341. The _psp variable contains the logical 32-bit address of the PSP of the
  342. program, and the _environ variable contains the environment address.
  343.  
  344. Although you can access the interrupt vectors by using this method,
  345. we do not suggest doing this.
  346.  
  347.  
  348.     Also keep in mind that MS-DOS interrupt handlers use memory
  349.     addresses in the 1st mb of physical memory while your program
  350.     and its data are loaded beyond the 1st mb. DOS32 intercepts
  351.     and correctly handles some, but not all, calls to MS-DOS.
  352.     Thus, if you are using Intr() or MsDos() calls, or call MS-DOS from
  353.     the assembler, you will need to modify the code.
  354.  
  355.     Additional details about this and related subjects can be found in
  356.     DOS32.DOC and API.DOC in subdirectory DOS32.
  357.  
  358.              Calling conventions
  359.              -------------------
  360.  
  361. Calling conventions match those in Borland Pascal with the following
  362. differences:
  363.  
  364.      all parameters use 4 bytes on the stack, or a multiple of 4 (BP:2)
  365.  
  366.      all procedures must preserve the contents of registers ebx, ecx, edx,
  367.      ds, and es!
  368.  
  369.      the direction bit should be cleared after the exit from a procedure,
  370.      if it has been modified by it.
  371.  
  372.  
  373.                 Language syntax of TMT Pascal/Fast:
  374.                 -----------------------------------
  375.  
  376. While the Language syntax of TMT Pascal/Fast is in general compatible with
  377. BP 7.0, there are some differences. Below is the list, divided into three
  378. groups: limitations, extensions, and incompatibilities.
  379.  
  380.  
  381.    1. Limitations:
  382.  
  383. Not implemented are MARK and RELEASE.
  384.  
  385. The INLINE() operator is implemented in a partial form:
  386.     INLINE (byte/byte/...);
  387. (No references to variables/constants are allowed).
  388.  
  389. The import of object modules does not support all 32bit object formats.
  390. We recommend using TASM which is fully supported (except for
  391. the use of segmented addresses, which is not needed in the flat model).
  392.  
  393.  
  394.    2. Extensions:
  395.  
  396. ADA-style comments are supported:  -- comment
  397. For example:
  398.  
  399.       space := ' ';  -- initialize filler char
  400.  
  401.  
  402.  
  403. Almost everywhere where Pascal's syntax allows a type identifier, we
  404. also allow a type descriptor. The compiler will produce a warning if you
  405. use this feature.
  406.  
  407. !!! Keep in mind that the rules of type equivalence stay in force.
  408.  
  409. Procedural values contain the address of the local environment (frame).
  410. Thus, any local procedures can be used in procedural values. Procedural
  411. declaration in the style
  412.  
  413.     procedure p (function f (a:real):real); ...
  414.  
  415. are also realized.
  416.  
  417.  
  418. The procedural value from a method of object can be obtained by
  419. selecting this method from some object value (not from a type). The
  420. parameters of this procedural value must match the parameters of the
  421. method.  The invocation of such a procedural value is an invocation of the
  422. corresponding method of the object.  The reference to the object is
  423. transferred through the base of the procedural value.
  424.  
  425. You can use only global procedural values to initialize a type constant.
  426.  
  427. !!! Procedural values may be used only while the environment where
  428. they were formed is still in existence.  Thus, for local procedures
  429. --- until the exit from the block, in which they are described; for
  430. methods --- while the underlying object still exists.
  431.  
  432. see also "incompatibilities."
  433.  
  434. With TMT Pascal you can use any statement as a procedure body,
  435. except for the assignment and the procedure calls.
  436.  
  437. The RESULT variable in the body of such functions denotes the variable
  438. that contains the return value.  The RESULT is of the function return type
  439. and may be used as a variable without any restrictions.
  440.  
  441. With TMT Pascal you can enter the procedure body directly as a procedure
  442. parameter.  The procedure or function header (if not specified) takes the
  443. procedural parameter type.  If the procedure header is specified, the
  444. procedure name is omitted.  Example:
  445.  
  446. function integral (function f (a:real):real; low, high, step: real): real;
  447. begin ... end;
  448.  
  449.     ...
  450.     writeln (integral (
  451.          function (x:real):real; begin result := sqrt (x) end,
  452.     0, 10, 0.1));
  453.  
  454.     writeln (integral (begin result := sqrt (a) end, 0, 10, 0.1));
  455.  
  456.     writeln (integral (
  457.          function;        -- function keyword needed
  458.              var x: real; -- for local declaration
  459.          begin x := sqrt (a); result := x end,
  460.     0, 10, 0.1));
  461.  
  462.     writeln (integral (
  463.          declare;         -- other way
  464.              var x: real; -- for local variable declaration
  465.          begin x := sqrt (a); result := x end,
  466.     0, 10, 0.1));
  467.  
  468. TMT Pascal allows exit from a local procedure to the one that contains it.
  469. This feature is listed in the Pascal's ANSI standard but not realized in
  470. BP. Together with procedural values, this is very useful for error handling:
  471.  
  472. Program test;
  473.     Var on_eof: procedure;
  474.     Function read_char: char;
  475.         Var c: char;
  476.     Begin
  477.         If Eof (Input) Then on_eof;
  478.         read (c);
  479.         read_char := c;
  480.     End;
  481.  
  482.     Procedure p;
  483.         Label eof_reached;
  484.         Procedure go_eof; Begin goto eof_reached; End;
  485.     Begin
  486.         on_eof := go_eof;
  487.         While True Do Write (read_char);
  488.     Eof_reached:
  489.         Writeln ('*** EOF ***');
  490.         on_eof := NIL;
  491.     End;
  492.  
  493. Begin
  494.     p;
  495. End.
  496.  
  497. Restriction: BREAK and CONTINUE operators cannot be used to exit
  498. from a procedure. Use GOTO instead.
  499.  
  500. Example:
  501.  
  502.         for i := 1 to 10 do
  503.             writeln (integral (  -- function integral from previous example
  504.                 if a < 0 then break else result := sqrt (a), -- incorrect
  505.             i, i + 1, 0.01));
  506.  
  507.         declare
  508.             label L;
  509.         begin
  510.             for i := 1 to 10 do
  511.                 writeln (integral (
  512.                     if a < 0 then goto L else result := sqrt (a), -- correct
  513.                 i, i + 1, 0.01));
  514.         L: end;
  515.  
  516. Functions may return any values of any type, including structures and arrays.
  517.  
  518.  
  519. The new operator DECLARE
  520.  
  521.    DECLARE
  522.        <declaration part>
  523.    BEGIN
  524.        <statement list>
  525.    END
  526.  
  527.  
  528. allows one to describe local variables and procedures anywhere in the
  529. program.  Use of "DECLARE" leads to more readable programs and conserves
  530. the stack space.
  531.  
  532. Functions length, chr, ord may be used as variables. For example:
  533.  
  534.          chr (i) := ' ';   is equivalent to   i := ord (' ');
  535.          ord (c) := 255;   is equivalent to   c := chr (255);
  536.          length (s) := 10; is equivalent to   s [0] := chr (10);
  537.  
  538.  
  539. The main program may contain "interface" and "implementation".
  540. This allows access to the variables of the main program from other
  541. modules:
  542.  
  543.     Program test;
  544.     Interface
  545.        Var global: Integer;
  546.     Implementation
  547.        Uses Unit_test;
  548.     Begin
  549.        Unit_test.write;
  550.     End.
  551.  
  552.     Unit Unit_test;
  553.     Interface
  554.         Procedure Write_global;
  555.     Implementation
  556.         Uses test;
  557.         Procedure Write_global;
  558.         Begin
  559.             Write (test.global);
  560.         End;
  561.     End.
  562.  
  563.  
  564. !!! Here the name of the file that contains the text of the main program
  565. must be identical with the name that follows the keyword "program".
  566.  
  567. New type: DWORD - an unsigned 32-bit integer (same as unsigned long in C).
  568. It can be useful in many cases, but keep in mind that during arithmetic
  569. operations between DWORD's and LONGINT's both arguments are cast to
  570. LONGINT's. This may cause an error.
  571.  
  572. ABSOLUTE may refer to fields of records and objects.  Also, the
  573. address of a global record/object field can be used within the initialization
  574. of typed constants.  Furthermore one can use recursive initialization:
  575.  
  576. type rec = record
  577.                next: ^rec;
  578.                buffer: array [1..10] of char;
  579.                buf_adr: pointer;
  580.            end;
  581.  
  582. const cyclic: rec = (next: @cyclic; buf_adr: @cyclic.buffer);
  583.  
  584. In initialization of structures and objects the fields may go in
  585. an arbitrary order. If a field is not listed, it is zeroed up.
  586.  
  587. The syntax of the STR operator has been extended:
  588.  
  589.     STR (value[:width[:precision]], ..., dest);
  590.  
  591. Here STR (name:2, ':', ext:3, dst); is equivalent to
  592.  
  593.         STR (name:2, temp1);
  594.         STR (':',    temp2);
  595.         STR (ext:3,  temp3);
  596.         dst := temp1 + temp2 + temp3;
  597.  
  598. Negative field widths in WRITE, WRITELN, and STR left align the value within
  599. its field.
  600.  
  601. !!! The Strings unit contains additional functions which may be more
  602.     convenient than the STR operator.
  603.  
  604.  
  605. +++0.30
  606.  
  607.      Multidimensional open arrays:
  608.  
  609. You can now use in procedure parameters and functions descriptions
  610. "array (<dim>) of <type>", where <dim> is a positive integer constant, defining
  611. the number of dimensions, ánd <type> is the type of the array elements.
  612. To determine the upper bounds of the array, use the "high (array)" function.
  613. It returns a vector of longints ("array [0..<dim>-1] of longint") containing
  614. the upper bounds. The lower bounds are always set to 0. The vector of the lower
  615. bounds can be obtained with a similar function "low".
  616.  
  617. Example:
  618.  
  619.  
  620. procedure print_vector (v: array (1) of double);
  621. var i: integer;
  622. begin
  623.     for i := 0 to high (v) [0] do write (v [i]:10:6, ' ');
  624.     writeln;
  625. end;
  626.  
  627. procedure print_matrix (m: array (2) of double);
  628. var i: integer;
  629. begin
  630.     for i := 0 to high (m) [0] do print_vector (m [i]);
  631.     writeln;
  632. end;
  633.  
  634. const a: array [1..3, 1..3] of double = ((1,0,2),(2,1,0),(1,2,1));
  635.  
  636. begin
  637.     print_matrix (a);
  638. end.
  639.  
  640. You can find an example program for solving a system of linear equations in
  641. the directory "EXAMPLES\LIN_EQ".
  642.  
  643. ---0.30
  644.  
  645.     3. Incompatibilities:
  646.  
  647. Procedural values is 8 bytes long and has the following format:
  648.  
  649. 0   +-----------------------+
  650.     | The entry point       |
  651. 4   +-----------------------+
  652.     | The local environment |
  653. 8   +-----------------------+
  654.  
  655. However, a pointer to a procedure is only 4 bytes long and contains only the
  656. address of the entry point. The @ operator verifies that the procedure is
  657. global. Otherwise a range error is generated.
  658.  
  659. Furthermore, the stack frame structure and parameter passing conventions
  660. differ from those in BP.
  661.  
  662. Thus the approach used in TVision and CLassLib for writing iterators
  663. cannot be used. However, we offer this correct and reliable (and more
  664. standard) way:
  665.  
  666.      Type list = object
  667.                      next: ^list;
  668.                      procedure for_all (procedure body (var v));
  669.                  end;
  670.  
  671.      Procedure list.for_all;
  672.          Var p: ^list;
  673.      Begin
  674.          p := @self;
  675.          repeat
  676.              body (p);
  677.              p := p^.next;
  678.          end;
  679.      End;
  680.  
  681.      ...
  682.  
  683.      Type int_list = object (list)
  684.                          value: integer;
  685.                          function first_positive: ^int_list;
  686.                      end;
  687.  
  688.      Function int_list.first_positive;
  689.          Label OK;
  690.          Var res: ^int_list;
  691.          Procedure do_item (var v);
  692.          Begin
  693.              If int_list (v).value > 0 Then
  694.              Begin
  695.                  res := @v;
  696.                  GoTo OK;
  697.              End
  698.          End;
  699.      Begin
  700.          res := nil;
  701.          for_all (do_item);
  702.      OK:
  703.          first_positive := res;
  704.      End;
  705.  
  706.      ...
  707.  
  708.  
  709.  
  710. Since in the flat model there are no segments, SEG() always returns 0,
  711. while PTR() ignores its first parameter.
  712.  
  713. !!! Be careful with these functions: in practice, any use of PTR() or SEG()
  714.     in your program may require a program modification.
  715.  
  716. Pseudo-array Mem and MemW are used as follows:
  717.  
  718.     i := MemW [<linear address>]
  719.  
  720. Note that the segment is not given.  Furthermore, the pseudo-arrays
  721. MemD and PortD of type DWORD are available.
  722.  
  723. See "Memory organization" for more details.
  724.  
  725.            Built-in assembler
  726.            ------------------
  727.  
  728. The built-in assembler of TMT Pascal Lite is 32-bit.  It is compatible
  729. with the BP's built-in assembler with the following differences:
  730.  
  731. Since the program created by the Pascal Lite is executed in the flat
  732. model, the far call and jump commands as well as the @Code and @Data symbols
  733. are not implemented.
  734.  
  735. The ret command:
  736.  
  737. The ret command without arguments is considered as a ret <parameter block
  738. size> command.  If you need to write the ret command without size you should
  739. set 0 explicitly:
  740.  
  741.       ret 0
  742.  
  743. Code-procedure
  744.  
  745. Besides the assembler-routine you can use the code-routine.  It has the
  746. following differences: the compiler doesn't emit the frame command on
  747. enter and return from the routine (including the ret command), and the local
  748. parameters are based on ESP on the moment of entry.
  749.  
  750. Example:
  751.  
  752.     function hi (n: word); code;
  753.     asm
  754.         mov al, byte ptr [n+1]
  755.         ret
  756.     end;
  757.  
  758.  
  759.            Supplied units:
  760.            ---------------
  761.  
  762. The following units are included:
  763.      SYSTEM.FPx - standard library functions
  764.         DOS.FPx - MS-DOS and OS/2 system interface.
  765.                   Corresponds to the DOS unit of BP.
  766.         CRT.FPx - Text mode screen interface.
  767.                   Corresponds to the CRT unit of BP.
  768.       USE32.FPx - Define type Integer as 32-bit etc.
  769.    ERRCODES.FPx - Run-time error codes.
  770.       DEBUG.FPx - Some debugging code.
  771.     STRINGS.FPx - String handling functions.
  772.                   Corresponds to the STRINGS unit of BP.
  773.      OS2ORD.FPx - contains ordinal numbers for OS/2 functions
  774.     DOSCALL.FPx - contains declaration OS/2 API procedures
  775.    OS2PMAPI.FPx - contains declaration OS/2 PM API procedures
  776.  
  777. Besides these modules, the distribution includes DOSCALL.FPD and ARG.FPD,
  778. which are needed for linkage.  These modules should not be called by the user.
  779.  
  780.  
  781.            The DOS Unit
  782.            ------------
  783.  
  784. This corresponds to the DOS unit of BP.
  785.  
  786. Differences:
  787.  
  788.  Type FarPointer = record ofs: pointer; seg: word end;
  789.  
  790.  The function GetIntVec has the following syntax:
  791.      procedure GetIntVec (IntNo: Byte; var Vector: FarPointer);
  792.  
  793.  and not
  794.      procedure GetIntVec (IntNo: Byte; var Vector: Pointer);
  795.  
  796.  New procedures:
  797.  
  798.      procedure GetIntVecFar (IntNo: Byte;   var Vector: FarPointer);
  799.      procedure SetIntVecFar (IntNo: Byte; const Vector: FarPointer);
  800.  
  801.     GetIntVec is equivalent to GetIntVecFar().
  802.  
  803.     SetIntVec is equivalent to SetIntVecFar(), but uses in the segmented
  804.       address the current CS.
  805.  
  806. A header of an interrupt procedure should have the following form:
  807.  
  808. procedure handler (
  809.     eip, eax, ecx, edx, ebx, esp, ebp, esi, edi: dword;
  810.     gs, fs, es: word
  811. ); interrupt;
  812.  
  813.  
  814. The Registers type has this structure:
  815.  
  816.  type Registers =
  817.     record
  818.         edi, esi, ebp, _res : dword;
  819.     case boolean of
  820.         true:  (ebx, edx, ecx, eax: dword;
  821.                 flags, es, ds, fs, gs, ip, cs, sp, ss: word);
  822.         false: (bl, bh, b1, b2, dl, dh, d1, d2, cl, ch, c1, c2, al, ah: byte);
  823.     end;
  824.  
  825.  
  826.  
  827. !!! When using Intr() and MsDos(), keep in mind that the DOS
  828.     interrupt handlers can deal only with the addresses from the 1st
  829.     megabyte of memory.
  830.  
  831.  
  832.            The CRT unit
  833.            ------------
  834.  
  835. This unit corresponds to the CRT unit of BP.
  836.  
  837.            The USE32 unit
  838.            ------------
  839.  
  840. This unit contains redefinitions of integer types for 32-bit computing as follow:
  841.  
  842.     type
  843.       SmallInt   = System.Integer;
  844.       SmallWord  = System.Word;
  845.       Integer    = System.Longint;
  846.       Word       = System.Longint;
  847.  
  848.     const
  849.       MaxInt     = high(longint);
  850.  
  851.     type
  852.       PByte      = ^Byte;
  853.       PWord      = ^Word;
  854.       PLongint   = ^Longint;
  855.       PSmallInt  = ^SmallInt;
  856.       PSmallWord = ^SmallWord;
  857.  
  858.  
  859.            The ERRCODES unit
  860.            -----------------
  861.  
  862. This unit contains constants for error codes, given by RUNERROR(),
  863. and the error_msg(code: Word): String, function that decyphers the error code.
  864.  
  865.  
  866.            The DEBUG unit
  867.            --------------
  868.  
  869. This module prints out the error code and the call stack in case of a
  870. run-time error. The stack is printed as follows:
  871.  
  872. RunError #201 (range check error)
  873. Calls stack:
  874. SYSTEM.BOUND_ERROR [chk_fun.inp(21) at 0000000A]
  875. TEST.ASSN [TEST.PAS(61) at 00000015]
  876. TEST.TEST [TEST.PAS(82) at 0000001D]
  877.  
  878. To use DEBUG, simply list it in the USES clause of the main program.
  879.  
  880. This module is supplied with source.
  881.  
  882. Using the debug UNIT increases the .exe module size
  883.  
  884. !!! Note: call of a procedure with a NULL address is currently diagnosed as
  885.     an arithmetic overflow.
  886.  
  887.            The STRINGS unit
  888.            ----------------
  889.  
  890. This unit corresponds to the STRING unit of BP.
  891. It also contains additional functions:
  892.  
  893. Function hex (n: DWord   ): String [12];
  894.     -- prints the argument in hex.
  895.  
  896. Function whl (n: LongInt ): String [12];
  897.     -- prints the argument as a signed integer.
  898.  
  899. Function uns (n: DWord   ): String [12];
  900.     -- prints the argument as an unsigned integer.
  901.  
  902. Function fix (x: Extended; pr: LongInt): String [15];
  903.     -- prints a real with fixed point. pr is the number of digits after the
  904.        decimal point.
  905.  
  906. Function align (str: String; width: LongInt): String;
  907.     -- pads the argument up to width with spaces.
  908.        spaces are on the right if width>0, and on the left otherwise.
  909.  
  910.            The OS2ORD unit
  911.            ---------------
  912.  
  913. This unit is valid only for OS/2. It contains ordinal number for
  914. OS/2 system DLLs
  915.  
  916.  
  917.            The DOSCALL unit
  918.            ----------------
  919.  
  920. This unit is valid only for OS/2. It contains the declaration of the OS/2
  921. API system procedures.
  922.  
  923.            The OS2PMAPI unit
  924.            -----------------
  925.  
  926. This unit is valid only for OS/2. It contains the declaration of the OS/2
  927. presentation manager API procedures.
  928.  
  929.  
  930.                    Possible problems during usage
  931.                    ------------------------------
  932.  
  933.  
  934.     DOS/Ext programs, generated by TMT Pascal, abend under OS/2. Correction:
  935.      - ensure that in "memory settings" the EMS_MEMORY_LIMIT is not equal to 0.
  936.  
  937.  
  938. +++0.33
  939.                    Run-time errors codes
  940.                    -------- ------ -----
  941.  
  942.   1    Invalid function number
  943.   2    File not found
  944.   3    Path not found
  945.   4    Too many open files
  946.   5    File access denied
  947.   6    Invalid file handle
  948.  12    Invalid file access_code
  949.  15    Invalid drive number
  950.  16    Cannot remove current directory
  951.  17    Cannot rename across drives
  952.  18    No more files
  953. 100    Disk read error
  954. 101    Disk write error
  955. 102    File not assigned
  956. 103    File not open
  957. 104    File not open for input
  958. 105    File not open for output
  959. 106    Invalid numeric format
  960. 150    Disk is write protected
  961. 151    Bad drive request struct length
  962. 152    Drive not ready
  963. 154    CRC error in data
  964. 156    Disk seek error
  965. 157    Unknown media type
  966. 158    Sector not found
  967. 159    Printer out of paper
  968. 160    Device write fault
  969. 161    Device read fault
  970. 162    Hardware failure
  971. 200    Division by zero
  972. 201    Range check error
  973. 202    Stack overflow error
  974. 203    Heap overflow error
  975. 204    Invalid pointer operation
  976. 205    Floating point overflow
  977. 206    Floating point underflow
  978. 207    Invalid floating point operation
  979. 208    Overlay manager not installed
  980. 209    Overlay file read error
  981. 210    Object not initialized
  982. 211    Call to abstract method
  983. 212    Stream registration error
  984. 213    Collection index_out of range
  985. 214    Collection overflow error
  986. 215    Arithmetic overflow error
  987. 216    General protection fault
  988. 217    Invalid operation_code
  989. 300    File io error
  990. 301    Nonmatched array bounds
  991. 302    Non local procedure pointer
  992. 303    Procedure pointer out of scope
  993. 304    Function not implemented
  994. 305    Breakpoint error
  995. 306    Break by ctrl/C
  996. 307    Break by ctrl break
  997. 308    Break by other process
  998. 309    No floating point coprocessor
  999.  
  1000. ---0.33
  1001.